The Developer's Guide PDF file shipped with ODF release 1 contains several inaccuracies which could not be updated in time. Please check the ODF web page at /www.devtools.apple.com/odf/ where we will post an updated version of the Developer's Guide as soon as possible or use this document (and the various Engineering Notes) to make sure that you have the latest information.
In general the sample code listings taken directly from an ODF class (i.e. starting with FW_) or an ODF example may be a little bit out of date, so we recommend that you open the corresponding source file or use a class browser to check the correct implementation.
Chapter 3. Handling Events
Page 64-65. Handling Virtual key Events
The code listing 3-2 is out of date:
• You don't need to shift the keyCode returned by GetKeyCode:
short keyCode = theVirtualKeyEvent.GetKeyCode(ev);
// short shiftedCode = keyCode >> 8; this bug was fixed in ODF 1
• The keyCode constants have been modified to follow ODF naming conventions (see FWEveDef.h)
FW_BACKSPACE -> FW_kVKBackspace
FW_RIGHT -> FW_kVKRight
FW_ENTER -> FW_kVKEnter
Page 70. Handling Activation Events
This section omits to explain the 2 kinds of activation occuring in parts:
1) The window activation, which is the traditional activate/deactivate events sent by the Mac OS when a window comes to the front or is pushed behind.
2) the part activation in the OpenDoc sense when a part's frame acquires the selection focus.
For a general discussion on OpenDoc activation, please see the OpenDoc Programmers Guide : Mouse Events, Activation and Dradding page 198, and UI Guidelines on Activation page 559.
ODF dispatches the DoActivateEvent method in response to window activation. You can use this method in your views (including your frames) to change the highlighting of a particular object. For instance ODF activates/deactivates scrollbars when the window becomes active/inactive to follow the Macintosh HI guidelines.
The code listing 3-8 is out of date: DoActivateEvent returns void instead of FW_Boolean, activate events are always propagated to all the views.
Page 71. Responding to Activations
As noted above this section should distinguish between window and part activation. The methods IsActive, Activate and Deactivate don't exist anymore.
In response to window activation ODF transfer the selection focus to the frame which last had it before the window was deactivated (Note: if the window is activated in response to a mouse-down event, the selection focus was already transferred to the frame where the event occured).
When your part receives an activation its main responsibility is to highlight the current selection, if it has the selection focus. For example the Container sample draws selection handles around its embedded parts. It implements DoActivateEvent to respond to the window activation and overrides FocusStateChanged to respond to part activation:
Note: See also the update below regarding part activation when the user click in a view outside the active frame.
Chapter 4. Managing Your Part's Interface
Page 84-85. Working With Views
The term container view should be replaced by parent view to avoid any confusion with container parts. A parent view is an instance of the class FW_CSuperView, its main difference with a normal view is that it can contain other subviews and can scroll. It is not a container in the OpenDoc sense, i.e. doesn't allow embedding of other parts (the property of embedding must be implemented at the frame level with the class FW_CEmbeddingFrame).
Page 85. Add section explaining the concept of content view
A frame contains a special view called the content view used to display the part’s content and to embed other parts. There can only be 1 content view per frame because its coordinate space is defined by the frame’s internal transform maintained by OpenDoc. In figure 4-3, page 86, the content view is the gray area containing the visible portion of the bitmap. Because the content view displays the part's content it is the only view which can scroll within the frame, see "Scrolling Your View" below.
By default a FW_CFrame object is created as being its own content view. You don't need to change anything if your part's content doesn't require scrolling within that frame. However, if you want to define a scrolling area to display your content it is necessary to create a subview as the content view and create two scrollbar views.
Content views can be created by code or by resources. You must first define your own subclass of FW_CSuperView. If you are implementing your frame's CreateSubViews method this is where you create an instance of your subclass and call the MakeContentView method. If you are using view resources you must define a resource type for your subclass and list a view of that type in your FW_RFrameLayout resource, with the value 1 for its contentView flag. See the Container or Form samples.
Be sure to set the scrollingDirection field to FW_kXYScrolling.
You don’t need to keep the content view as a class field because that’s already done in FW_CFrame. You can retrieve it later with GetContentView():
contentView = myCFrame->GetContentView(ev);
Use IsContentView(ev) and IsInContentView(ev) to test if a view is the content view or is inside the content view.
Page 85. Add note on part activation when clicking in views
If the user clicks in a view belonging to a non active frame (i.e. non active part) several things can occur:
• If the frame belongs to a non-active window the window is first activated.
• If the frame is not the root frame, i.e. is embedded inside another frame, then it is first activated.
• If the frame is the root frame, then it is activated only if the view wants to become the target. In ODF 1 only edit-views and list-boxes can become the target (i.e. process key events), clicking in such views must activate their frame in order for them to receive key events. On the other hand clicking on controls belonging to the root frame won't activate it.
A future release of ODF will provide more flexibility for managing part and frame activation when handling mouse events in views. The acceptable behavior can depend on your part's content, there is no strict HI guideline at this level of granularity.
Page 85-86. View Coordinate Spaces
It should be noted that view coordinate space and view-content coordinate space are different only for superviews whose extent is bigger than their bounds size (i.e. supports scrolling). In cases of simple views, or superviews with an extent equal to their bound size, there is only 1 coordinate space.
Note: if a view extent is smaller than its bounds size you can still draw outside the extent within the bounds rectangle. For instance the content view of a drawing program could have a small drawing area and a gray region outside.
See ODF Draw for an example using rulers.
Page 87-88. Defining a Subview
The view hierarchy inside your frame will never be very deep. Usually a frame contains simple views, such as controls, as direct children, and it may contain a content view which itself contains other simple views. It is rare that you use more than 2 layers of views because of the limitation
Note: in order to group several views together visually, such as several radio buttons, consider using a FW_CGroupBox object, it's simpler than creating a parent view just for this visual effect. However creating your own FW_CSuperView class for that purpose allows you to customize its drawing and manage the layout management of its subviews.
Page 88-93. Creating Subviews (and ajusting the view layout)
This section doesn't talk about creating views from resources instead of implementing CreateSubViews. It is a simpler and more maintainable way of dealing with your part's interface. See the Engineering note "Defining Views in resources" and the Form or Container samples (When you pass a resource id to your frame's constructor its method CreateSubViews won't be called.)
Listing 4-5 for CFormFrame::CreateSubViews is an old version. You should go directly to the current code in ODF:Form:Sources:Frame.cpp and ODF:Form:Sources:FormView.cpp
The method AdjustSubViews doesn't exist anymore and listing 4-6 is obsolete. The Form sample uses the ODF built-in layout management for most of its views and implements CFormView::AdjustToNewLayout for centering the content view. See the Engineering note "Layout Management" for more information.
Page 93-95. Adding Controls to Your View
This section is superseded by the Engineering note "Using Controls".
Controls are easier to define in resources like all views. The method AdjustSubViews doesn't exist anymore. The layout of controls is managed by the view binding flag as described in the Engineering note "Layout Management". By default buttons and popup menus keep fixed bounds and scrollbars follow the right and bottom edge of their parent view.
The method SetDefault doesn't exist anymore and the class FW_CPushButton has been merged in FW_CButton. The sample code to create a push button on page 94 should be replaced by:
Note that you must use the macro FW_NEW instead of new because all views are auto-destruct objects. The button kind is FW_kPushButton and the control's message is FW_kDefaultButtonMsg. Using this message is enough to indicate that you want it to be drawn as a default button.
Chapter 7. Data Interchange
Pages 250-251. Making Your Selection Publishable
The code listings are out of date:
Listing 7-45 Verifying whether a selection can be published
for (CBaseShape *shape = ite.First(); ite.IsNotComplete();
shape = ite.Next())
{
if (shape->IsInLinkDestination(ev))
{
result = FALSE;
break;
}
else if (shape->IsPublished()) // don't allow a shape to be
// ]published more than once
{
result = FALSE;
break;
}
}
return result;
}
FW_CSelection also defines the method CanPasteAsLink. This method is similar in function to the IsSelectionLinkable method, except that you can use this method to specify the preferred method of linking this data, whether that be by merging or embedding the data. Potential merge options include the following:
• kODPasteAsEmbed
• kODPasteAsEmbedOnly
• kODPasteAsMerge
• kODPasteAsMergeOnly
Listing 7-46 shows the CanPasteAsLink method of CDrawSelection. This method returns the constant kODPasteAsMerge so that ODF will attempt to merge the selected data by default.
Listing 7-46 Verifying that your part can subscribe to data
// Check whether the storage unit contains mergeable content
if (su->Exists(ev, kODPropContents, fDrawPart->GetPartKind(ev), 0))
setting = kODPasteAsMerge;
else // foreign content - cannot be merged
setting = kODPasteAsEmbedOnly;
return fAllowLink;
}
Page 252. Add section on Link Borders and Selection
The two classes representing links, FW_CLinkSource and FW_CLinkDestination, are now derived from a common base class. FW_CLink provides an API for implementing link borders and link selection, although support for these features in ODF is incomplete.
To implement link borders, override DoCreateLinkBorderShape and DoDrawLinkBorder. In DoCreateLinkBorderShape create and return a shape representing the border around the linked data. In DoDrawLinkBorder use this shape to draw the actual border.
See the classes CTableLink and CTableLinkSources in the Table sample for examples of overriding DoCreateLinkBorder and DoDrawLinkBorder.
To determine whether the user clicked on a link border, call IsMouseInBorder from your DoMouseDown method. Call IsLinkSelected to determine whether the link was already selected, and then call Select to change the link’s selection state.
Chapter 9. Programming Services
Page 312-314. Using the Notifications Subsystem
This section is superseded by the Engineering note "Notification" in the folder Engineering Notes:Foundation:
